<HTML>
<BODY BGCOLOR=white>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->
NAME
     sge_gdi, sge_gdi_setup, sge_gdi_shutdown - Grid  Engine  GDI
     calls

SYNOPSIS
     #include "sge_gdi.h"

     int sge_gdi_setup( char *programname );

     lList *sge_gdi(
          u_long32 target,
          u_long32 command,
          lList** lpp,
          lCondition* cp,
          lEnumeration* enp,
     );

     int sge_gdi_shutdown( void );

DESCRIPTION
     The Grid Engine Database Interface (GDI) provides the neces-
     sary  means to interface important Grid Engine functionality
     directly from inside  user  applications.  Among  the  func-
     tionality  being  interfaced  by  the  Grid  Engine  GDI are
     retrieving status information of jobs and  queues,  changing
     configuration values, submitting and deleting jobs, suspend-
     ing and enabling queues, and the like.

     The Grid Engine GDI is based upon the internal  data  struc-
     tures representing Grid Engine managed objects such as jobs,
     hosts, queues, queue complexes, scheduling events,  schedul-
     ing  orders  or  user  access lists. These objects are main-
     tained within Grid Engine by use of generic linked lists.  A
     rich  set  of routines is available to manipulate such lists
     (see <B><A HREF="../htmlman3/list_intro.html">list_intro(3)</A></B>).  The lists can either be accessed simi-
     lar  to  the  regular  computer  science linked lists, or an
     advance access mode is used, which allows for  viewing  upon
     the  Grid  Engine  managed  objects  as  database tables and
     access them with SQL-like operations such as <I>select</I> or <I>join</I>.

     There is only one central routine in the Grid Engine GDI  to
     retrieve  Grid  Engine  objects  from  <B><A HREF="../htmlman8/sge_qmaster.html">sge_qmaster(8)</A></B> and to
     register changes: <I>sge</I>_<I>gdi</I>. As soon as  Grid  Engine  objects
     have  been obtained in an application the generic list mani-
     pulation routines (see  <B><A HREF="../htmlman3/list_intro.html">list_intro(3)</A></B>)  are  used  to  apply
     changes or to retrieve information from the objects.

     The following is a description of the basic functionality of
     all Grid Engine GDI functions:

  sge_gdi_setup
     Registers a program for usage of the Grid Engine  GDI.   The
     parameter programname is used for error and warning messages
     to identify the originator, On success 0 is returned.

  sge_gdi
     Access an object or part thereof managed by Grid Engine.
     <I>sge</I>_<I>gdi</I> returns a generic list reporting success/failure  of
     the intended operation. This list gets allocated by <I>sge</I>_<I>gdi</I>.
     The caller is responsible for freeing using <B><A HREF="../htmlman3/lFreeList.html">lFreeList(3)</A></B>
     A list is returned because <I>sge</I>_<I>gdi</I> itself  executes  complex
     operations  with  lists  and  a  different return status may
     occur for  each  element  of  the  manipulated  Grid  Engine
     object.
     A possible response is a list  element  containing  a  field
     with a status value (AN_status). The value STATUS_OK is used
     in case of success. STATUS_OK and other values  are  defined
     in   the   include  file  sge_answerL.h.  The  second  field
     (AN_text) in a  response  list  element  is  a  string  that
     describes  the  performed  operation  or a description of an
     error.
     Each call of  <I>sge</I>_<I>gdi</I>  passes  a  list  with  at  least  one
     response  to  the caller. The response list of a get command
     (see below) contains only one element reporting  success  or
     failure.  In  the  other cases one response list element for
     each element in the argument list is produced.

     The function arguments have the following meaning:

     target
          Refers to a Grid Engine managed object.  The  following
          Grid Engine objects are accessible currently (the names
          in round brackets denote the identifiers to be used for
          target):                 jobs                (JB_Type),
          execution/administration/submit                   hosts
          (EH_Type/AH_Type/SH_Type), queues (QU_Type), queue com-
          plexes (CE_Type), scheduling events (EV_Type), schedul-
          ing orders (OR_Type) and user access lists (AC_Type).

     command
          Specifies the operation to be  executed.  Valid  values
          are SGE_GDI_GET (for retrieving an object), SGE_GDI_ADD
          (for adding elements to an  object),  SGE_GDI_DEL  (for
          deleting  elements from an object) and SGE_GDI_MOD (for
          modifying elements of an object).

     lpp  This parameter is used to get a list  in  case  of  the
          SGE_GDI_GET command.  The necessary memory for the list
          is allocated  by  <I>sge</I>_<I>gdi</I>.   The  caller,  however,  is
          responsible  for  freeing  the  memory by using <I>lFreeL-</I>
          <B><A HREF="../htmlman3/ist.html">ist(3)</A></B>.  In the other cases the caller  passes  a  list
          pointer     referencing     the    elements    to    be
          added/deleted/modified  from  the  corresponding   Grid
          Engine  managed  object.   <I>sge</I>_<I>gdi</I>  does  not  free the
          passed list.

     cp   Points to a lCondition as it is built by  <B><A HREF="../htmlman3/lWhere.html">lWhere(3)</A></B>  in
          case   of   the  SGE_GDI_GET  command.  This  condition
          describes a profile of the elements to be contained  in
          the  list.   It is used to access only a part of a Grid
          Engine object.  Has to be NULL in other cases.

     enp  Points to a lEnumeration structure built by <B><A HREF="../htmlman3/lWhat.html">lWhat(3)</A></B> in
          case   of  the  SGE_GDI_GET  command.  The  enumeration
          describes the fields in the requested list. It is  used
          to define a subset of the list. Has to be NULL in other
          cases.

  sge_gdi_shutdown
     This function cancels registration of a  program  using  the
     Grid Engine GDI. On success 0 is returned.

SEE ALSO
     <B><A HREF="../htmlman1/sge_intro.html">sge_intro(1)</A></B>, <B><A HREF="../htmlman3/list_intro.html">list_intro(3)</A></B>.

COPYRIGHT
     See <B><A HREF="../htmlman1/sge_intro.html">sge_intro(1)</A></B> for a full statement of rights and  permis-
     sions.




























</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>
